base-x

What is base-x?

The base-x npm package is designed for encoding and decoding of non-standard base representations. It is commonly used for converting between binary data and a variety of alphanumeric representations using different base encodings, such as base58 used in Bitcoin addresses.

What are base-x's main functionalities?

Encoding binary data to a specified base

This feature allows you to encode binary data (like a Buffer) into a string representation using a custom base alphabet. The example shows encoding 'Hello World' to a base58 string.

"const baseX = require('base-x');\nconst BASE58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';\nconst bs58 = baseX(BASE58);\nconst encoded = bs58.encode(Buffer.from('Hello World'));\nconsole.log(encoded); // Prints encoded string in base58"

Decoding a base-encoded string to binary data

This feature allows you to decode a string that was encoded in a custom base back into binary data. The example demonstrates decoding a base58 string back to its original binary form.

"const baseX = require('base-x');\nconst BASE58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';\nconst bs58 = baseX(BASE58);\nconst decoded = bs58.decode('JxF12TrwUP45BMd');\nconsole.log(decoded); // Prints Buffer containing the original binary data"

Other packages similar to base-x

base58

The base58 npm package is specifically tailored for base58 encoding and decoding, similar to one of the use cases of base-x. However, base-x is more flexible as it supports custom bases, whereas base58 is fixed to the base58 alphabet.

bs58

bs58 is another package that provides similar functionality to base-x but is specifically for base58 encoding and decoding. It is less flexible than base-x because it does not allow for custom alphabets.

multibase

multibase is a package that supports multiple base encodings and is part of the multiformats family. It is more comprehensive than base-x as it supports a variety of bases out of the box and follows the multibase specification.

README

base-x

Fast base encoding / decoding of any given alphabet using bitcoin style leading zero compression.

WARNING: This module is NOT RFC3548 compliant, it cannot be used for base16 (hex), base32, or base64 encoding in a standards compliant manner.

Example

Base58

var BASE58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
var bs58 = require('base-x')(BASE58)

var decoded = bs58.decode('5Kd3NBUAdUnhyzenEwVLy9pBKxSwXvE9FMPyR4UKZvpe6E3AgLr')

console.log(decoded)
// => Uint8Array(33) [
//   128, 237, 219, 220,  17, 104, 241, 218,
//   234, 219, 211, 228,  76,  30,  63, 143,
//    90,  40,  76,  32,  41, 247, 138, 210,
//   106, 249, 133, 131, 164, 153, 222,  91,
//    25
// ]

console.log(bs58.encode(decoded))
// => 5Kd3NBUAdUnhyzenEwVLy9pBKxSwXvE9FMPyR4UKZvpe6E3AgLr

Alphabets

See below for a list of commonly recognized alphabets, and their respective base.

Base	Alphabet
2	01
8	01234567
11	0123456789a
16	0123456789abcdef
32	0123456789ABCDEFGHJKMNPQRSTVWXYZ
32	ybndrfg8ejkmcpqxot1uwisza345h769 (z-base-32)
36	0123456789abcdefghijklmnopqrstuvwxyz
58	123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
62	0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
64	ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/
67	ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_.!~

How it works

It encodes octet arrays by doing long divisions on all significant digits in the array, creating a representation of that number in the new base. Then for every leading zero in the input (not significant as a number) it will encode as a single leader character. This is the first in the alphabet and will decode as 8 bits. The other characters depend upon the base. For example, a base58 alphabet packs roughly 5.858 bits per character.

This means the encoded string 000f (using a base16, 0-f alphabet) will actually decode to 4 bytes unlike a canonical hex encoding which uniformly packs 4 bits into each character.

While unusual, this does mean that no padding is required and it works for bases like 43.

LICENSE MIT

A direct derivation of the base58 implementation from bitcoin/bitcoin, generalized for variable length alphabets.